<p></p>
<h1>Help Search Enhancements in Eclipse 3.2</h1>
<p>Dejan Glozic,
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%m/%d/%Y" startspan -->12/10/2005<!--webbot bot="Timestamp" endspan i-checksum="12499" --></p>
<h2>Background</h2>
<p>This document describes enhancements for the Eclipse search added in the 3.2 
time frame. The enhancements will first appear in 3.2 milestone 4 and will be 
subsequently refined until the final release. Consequently, we will update this 
document until the API freeze in M5 to reflect these refinements.</p>
<h2>The problem</h2>
<p>There were several new developments in Eclipse 3.2 that prompted us to beef 
up the search story in Eclipse.</p>
<h3>Dynamic Content Serving</h3>
<p>One of the major new additions to the help system in 3.2 release is dynamic 
content serving. Prior to 3.2, documents were considered static and the role of 
the Eclipse help system was to serve these documents to the web browser as-is. 
Since the content was static, it could not adapt to the workbench context (the 
operating system, active plug-ins, user role etc.). Content that was supposed to 
appear in several document could not be shared, and content could not be 
injected/contributed into existing documents via extensions.</p>
<p>Since 3.2, it will be possible to contribute XHTML documents enhanced with 
the additional Eclipse-specific grammar that provides for dynamic content 
filtering, reuse and contribution. The use of XHTML documents</p>
<h3>User Assistance content outside of the TOC</h3>
<p>Apart from the help system, there are other user assistance vehicles that 
serve content (e.g. cheat sheets and Welcome). This content was not indexed and 
therefore not part of the search. In addition to indexing it, it was important 
to preserve the fact that the search hits would need to be opened in a different 
way from regular help topics.</p>
<h3>Federated search engines with delegation of the 'open' command</h3>
<p>In 3.1, the assumption was that federated search engines are responsible for 
collecting search results and providing hrefs for the help system to open. 
However, experience has shown that some search engines have a different idea of 
what 'open' means to them and would like to handle that command.</p>
<h2>The solution</h2>
<p>As a solution for the above mentioned problems, we introduced a notion of 
search participants and tweaked the existing search APIs to be more flexible.</p>
<h3>Search participants</h3>
<p>Search participants are extensions to the Lucene indexing mechanism 
responsible for adding documents into the overall index that are out of reach of 
the current mechanism:</p>
<pre>&lt;extension point=&quot;org.eclipse.help.base.luceneSearchParticipant&quot;&gt;
   &lt;searchParticipant id=&quot;org.eclipse.myGlobalParticipant&quot;
     name=&quot;Global Participant&quot;
     icon=&quot;icons/mydoc.gif&quot;
     participant=&quot;org.eclipse.myPlugin.myPackage.MyGlobalParticipant&quot;/&gt;
   &lt;searchParticipant id=&quot;org.eclipse.myXYZParticipant&quot;
     extensions=&quot;xyz&quot;
     participant=&quot;org.eclipse.myPlugin.myPackage.MyXYZParticipant&quot;/&gt;
  &lt;/extension&gt;</pre>
<p>The example above shows two kinds of search participants. The first example 
registers a global participant responsible for introducing new documents into 
the index. These documents are not part of the TOC and would otherwise never be 
indexed. Cheat sheet and Intro plug-ins now both provide a global search 
participant that indexes cheat sheets and Intro pages. Name of the participant 
is used as a result category and also for scope settings in the search engine 
scope dialog. Optional icon attribute is used to render search results 
differently if the come from this search participant.</p>
<p>The second example shows content type search participant. It is used for 
documents that are part of the Help's TOC but have a format that Help cannot 
handle. These participants do not need to declare a different image or name, but 
must specify a comma-separated list of file extensions they will handle. Help 
system provides XHTML search participant that can be used by document plug-ins 
to complement the dynamic content producer that handles XHMTL TOC documents and 
transforms them dynamically.</p>
<p>Global search participants have global scope. In contrast, search 
participants declared for file extensions only work with content coming from 
their contributing plug-in. In order to use services of a content-sensitive 
search participant, other plug-ins must declare an explicit binding to them:</p>
<blockquote>
	<pre>&lt;extension point=&quot;org.eclipse.help.base.luceneSearchParticipant&quot;&gt;
    &lt;binding participantId=&quot;org.eclipse.myXYZParticipant&quot;/&gt;
&lt;/extension&gt;</pre>
</blockquote>
<p>This overhead was important to prevent viral effect of content-sensitive 
participants. Since they are given a chance to index a document of the extension 
they are registered for before the default help indexer, they can potentially 
take over indexing of all documents in the product. The notion of binding adds a 
degree of protection by only extending the visibility of these participants to 
plug-ins that allowed them in this way.</p>
<p>The attribute participant must has a value that represents a fully qualified 
name of the Java class that extends abstract class <code>LuceneSearchParticipant</code>. 
An abstract class rather than an interface has been selected in order to provide 
for an easier API evolution and also to provide some helper protected methods 
that subclasses can use. A very useful class for extenders will be <code>
XMLSearchParticipant</code> that greatly simplifies indexing of XML source 
files. It makes </p>
<h3>Enhancements to the existing classes</h3>
<p>New interfaces have been added to extend the existing <code>ISearchEngine</code> 
and <code>ISearchEngineResult</code>:</p>
<blockquote>
	<pre>public interface ISearchEngineResult2 extends ISearchEngineResult {
	String getId();
	URL getIconURL();
	boolean canOpen();
}</pre>
	<pre>public interface ISearchEngine2 extends ISearchEngine {
	boolean open(String id);
}</pre>
</blockquote>
<p>Engine results that implement <code>ISearchEngineResult2</code> have 
additional methods that give more freedom to search engines. A search result can 
now return a URL of the icon image to render the result. It can also return a 
unique id as an alternative to href. Finally, if it returns true from the <code>
canOpen</code> method, the help system will not try to open it itself. Instead, 
if the contributing search engine implements <code>ISearchEngine2</code>, it 
will delegate opening to the engine itself by passing the id of the result.</p>
<p>Notice how we chose to pass the id to the search engine rather than search 
result directly. This indirection makes bookmarking these types of hit results 
possible. If a search result returns true to <code>canOpen</code>, we don't 
store its href any more. Instead, we store the engine id and result id. This 
allows us to delegate bookmark opening to the contributing engine in the same 
way we do when opening from the search result view.</p>
<p>&nbsp;</p>
<p>&nbsp;</p>

